<!doctype html>
<html lang="en" class="page-type-section">
<head prefix="og: http://ogp.me/ns#">
<meta charset="utf-8">
<title>配置设置 - FreeMarker 手册</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="format-detection" content="telephone=no">
<meta property="og:site_name" content="FreeMarker 手册">
<meta property="og:title" content="配置设置">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://freemarker.org/docs/pgui_config_settings.html">
<link rel="canoical" href="http://freemarker.org/docs/pgui_config_settings.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css">
</head>
<body itemscope itemtype="https://schema.org/Code">
    <meta itemprop="url" content="http://freemarker.org/docs/">
    <meta itemprop="name" content="FreeMarker 手册">

  <!--[if lte IE 9]>
  <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
  <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org" role="banner">            <img itemprop="image" src="logo.png" alt="FreeMarker">
</a><ul class="tabs"><li><a href="http://freemarker.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="http://freemarker.org/docs/api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="http://freemarker.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://sourceforge.net/p/freemarker/bugs/new/" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="toc.html" class="navigation-header">Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="toc.html"><span itemprop="name">FreeMarker 手册</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui.html"><span itemprop="name">程序开发指南</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_config.html"><span itemprop="name">配置(Configuration)</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_config_settings.html"><span itemprop="name">配置设置</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div>    <div class="main-content site-width">
      <div class="content-wrapper">
  <div id="table-of-contents-wrapper" class="col-left">
      <script>var breadcrumb = ["FreeMarker 手册","程序开发指南","配置(Configuration)","配置设置"];</script>
      <script src="toc.js"></script>
      <script src="docgen-resources/main.min.js"></script>
  </div>
<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="pgui_config_sharedvariables.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_config_templateloading.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="pgui_config_settings" itemprop="headline">配置设置</h1>
</div></div><p><strong>Settings</strong>(配置设置)
		是影响FreeMarker行为的已被命名的值。配置设置有很多，
		例如：<code class="inline-code">locale</code>，<code class="inline-code">number_format</code>，
		<code class="inline-code">default_encoding</code>，
        <code class="inline-code">template_exception_handler</code>。可以参考 <a href="http://freemarker.org/docs/api/freemarker/template/Configuration.html#setSetting-java.lang.String-java.lang.String-">
		<code>Configuration.setSetting(...)</code>的Java API 文档</a>
		来查看配置设置的完整列表。</p><p>配置设置存储在 <code class="inline-code">Configuration</code> 实例中，可以在 
        <code class="inline-code">Template</code> 实例中被覆盖。比如，在配置中给 
		<code class="inline-code">locale</code> 设置为 <code class="inline-code">&quot;en_US&quot;</code>，
		那么使用该配置的所有模板中的 
		<code class="inline-code">locale</code> 都使用 <code class="inline-code">&quot;en_US&quot;</code>，
		除非在模板中locale被明确地设置成其它不同的值(参见
		<a href="ref_directive_include.html#ref_directive_include_localized">localization</a>)。
		因此，在 <code class="inline-code">Configuration</code> 中的值充当默认值，
		这些值在每个模板中也可以被覆盖。在 <code class="inline-code">Configuration</code> 
		或 <code class="inline-code">Template</code> 实例中的值也可以在单独调用 
		<code class="inline-code">Template.process</code> 方法后被覆盖。
        对于每个调用了 <code class="inline-code">freemarker.core.Environment</code> 
		对象的值在内部创建时就持有模板执行的运行时环境，也包括了那个级别被覆盖了的设置信息。
		在模板执行时，那里存储的值也可以被改变，所以模板本身也可以设置配置信息，
		比如在输出中途来变换 <code class="inline-code">locale</code> 设置。</p><p>配置信息可以被想象成3层(<code class="inline-code">Configuration</code>，
		<code class="inline-code">Template</code>，<code class="inline-code">Environment</code>)，
		最高层包含特定的值，它为设置信息提供最有效的值。
		比如(设置信息A到F仅仅是为这个示例而构想的)：</p>  <div class="table-responsive">
    <table class="table">

          

          

          <thead>
            <tr>
              <th align="left"></th>


              <th align="center">Setting A</th>


              <th align="center">Setting B</th>


              <th align="center">Setting C</th>


              <th align="center">Setting D</th>


              <th align="center">Setting E</th>


              <th align="center">Setting F</th>

            </tr>

          </thead>


          <tbody>
            <tr>
              <td align="left">Layer 3: <code class="inline-code">Environment</code></td>


              <td align="center">1</td>


              <td align="center">-</td>


              <td align="center">-</td>


              <td align="center">1</td>


              <td align="center">-</td>


              <td align="center">-</td>

            </tr>


            <tr>
              <td align="left">Layer 2: <code class="inline-code">Template</code></td>


              <td align="center">2</td>


              <td align="center">2</td>


              <td align="center">-</td>


              <td align="center">-</td>


              <td align="center">2</td>


              <td align="center">-</td>

            </tr>


            <tr>
              <td align="left">Layer 1: <code class="inline-code">Configuration</code></td>


              <td align="center">3</td>


              <td align="center">3</td>


              <td align="center">3</td>


              <td align="center">3</td>


              <td align="center">-</td>


              <td align="center">-</td>

            </tr>

          </tbody>

            </table>
  </div>
<p>配置信息的有效值为：A=1，B=2，C=3，D=1，E=2。
		而F的设置则是 <code class="inline-code">null</code>，或者在你获取它的时候将抛出异常。</p><p>我们看看如何准确设置配置信息：</p><ul>
          <li>
            <p><code class="inline-code">Configuration</code> 层：
			原则上设置配置信息时使用 <code class="inline-code">Configuration</code> 
			对象的setter方法，例如：</p>

            

<div class="code-wrapper"><pre class="code-block code-unspecified">Configuration myCfg = new Configuration(Configuration.VERSION_2_3_23);
myCfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
myCfg.setDefaultEncoding(&quot;UTF-8&quot;);</pre></div>

            <p>在真正使用 <code class="inline-code">Configuration</code> 对象
			(通常在初始化应用程序时)之前来配置它，后面必须将其视为只读的对象。</p>

            <p>在实践中，比如很多Web应用框架中，就应该使用这种框架特定的配置方式来进行配置，
			比如使用成对的 <code class="inline-code">String</code> 来配置(像在 
			<code class="inline-code">.properties</code> 属性配置文件中那样)。
			在这种情况下，框架的作者大多数使用 <code class="inline-code">Configuration</code> 
			对象的 <code class="inline-code">setSetting(String name, String value) </code>方法。
			这可以参考<a href="http://freemarker.org/docs/api/freemarker/template/Configuration.html#setSetting-java.lang.String-java.lang.String-"><code>setSetting</code>的API文档</a>
			部分来获取可用的设置名和参数的格式的信息。
			而在Spring框架中，我们可以这样进行：</p>

            

<div class="code-wrapper"><pre class="code-block code-unspecified">&lt;bean id=&quot;freemarkerConfig&quot;
    class=&quot;org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer&quot;&gt;
  &lt;property name=&quot;freemarkerSettings&quot;&gt;
    &lt;props&gt;
      &lt;prop key=&quot;incompatible_improvements&quot;&gt;2.3.23&lt;/prop&gt;
      &lt;prop key=&quot;template_exception_handler&quot;&gt;rethrow&lt;/prop&gt;
      &lt;prop key=&quot;default_encoding&quot;&gt;UTF-8&lt;/prop&gt;
    &lt;/props&gt;
  &lt;/property&gt;
&lt;/bean&gt;</pre></div>

            <p>请注意，这种形式的配置( <code class="inline-code">String</code> 键-值对)
			和直接使用 <code class="inline-code">Configuration</code> 的API相比，
			很不幸地被限制了。</p>
          </li>

          <li>
            <p><code class="inline-code">Template</code> 层：对于被请求的本地化信息，模板的
            <code class="inline-code">locale</code> 设置由 
			<code class="inline-code">Configuration.getTemplate(...)</code> 来设置。
			否则，就不能在这里进行设置，除非想控制 <code class="inline-code">Template</code> 
			对象来代替 <code class="inline-code">freemarker.cache.TemplateCache</code>，这样的话，
			应该在 <code class="inline-code">Template</code> 对象第一次被使用前就设置配置信息，
			然后就将 <code class="inline-code">Template</code> 对象视为是只读的。</p>
          </li>

          <li>
            <p><code class="inline-code">Environment </code>层：这里有两种配置方法：</p>

            <ul>
              <li>
                <p>使用Java API：使用 <code class="inline-code">Environment</code> 
				对象的setter方法。当然想要在模板执行之前来做，然后当调用 
				<code class="inline-code">myTemplate.process(...)</code> 时会遇到问题，
				因为在内部创建 <code class="inline-code">Environment</code> 对象后立即就执行模板了，
				导致没有机会来进行设置。这个问题的解决可以用下面两个步骤进行：</p>

                

<div class="code-wrapper"><pre class="code-block code-unspecified">Environment env = myTemplate.createProcessingEnvironment(root, out);
env.setLocale(java.util.Locale.ITALY);
env.setNumberFormat(&quot;0.####&quot;);
env.process();  // process the template</pre></div>
              </li>

              <li>
                <p>在模板中(通常这被认为是不好的做法)直接使用 <a href="ref_directive_setting.html#ref.directive.setting"><code>setting</code>
                指令</a>，例如：</p>

                

<div class="code-wrapper"><pre class="code-block code-template">&lt;#setting locale=&quot;it_IT&quot;&gt;
&lt;#setting number_format=&quot;0.####&quot;&gt;</pre></div>
              </li>
            </ul>

            <p>在这层，当什么时候改变配置信息，是没有限制的。</p>
          </li>
        </ul><p>要知道 FreeMarker 支持什么样的配置信息还有它们的意义，
		可以先看看FreeMarker Java API文档中的下面这部分内容：</p><ul>
          <li>
            <p>在三层中 <code class="inline-code">freemarker.core.Configurable</code> 
			的setter方法来配置。</p>
          </li>

          <li>
            <p>只在 <code class="inline-code">Configuration</code> 层可用的
			<code class="inline-code">freemarker.template.Configuration</code> 
			的setter方法来配置。</p>
          </li>

          <li>
            <p>在三层中可用 <code class="inline-code">String</code> 键-值对书写的 
			<code class="inline-code">freemarker.core.Configurable.setSetting(String,String)</code>
			配置。</p>
          </li>

          <li>
            <p>只在 <code class="inline-code">Configuration</code> 层中可用 
			<code class="inline-code">String</code> 键-值对书写的 
			<code class="inline-code">freemarker.template.Configuration.setSetting(String, String)</code>
			配置。</p>
          </li>
        </ul><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_config_sharedvariables.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_config_templateloading.html"><span>Next</span></a></div></div></div></div>      </div>
    </div>
<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="http://freemarker.org/index.html">What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html">About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/nanlei/freemarker/tree/manual-zh-2.3-gae/src/manual">Chinese Manual on Github</a></li><li><a href="https://github.com/freemarker/freemarker">FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker">Follow us on Twitter</a></li><li><a href="https://sourceforge.net/p/freemarker/bugs/new/">Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker">Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html">Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="http://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"><p><span class="generated-for-product">Generated for: Freemarker 2.3.23</span><span class="last-updated"> Last generated:
<time itemprop="dateModified" datetime="2015-09-18T14:38:51Z" title="Friday, September 18, 2015 2:38:51 PM GMT">2015-09-18 14:38:51 GMT</time></span></p> <p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2015
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="http://freemarker.org">The FreeMarker Project</a>. All rights reserved. </p>
</div></div></div></body>
</html>
